home *** CD-ROM | disk | FTP | other *** search
llllffffmmmmtttt((((3333CCCC)))) llllffffmmmmtttt((((3333CCCC)))) NNNNAAAAMMMMEEEE _llll_ffff_mmmm_tttt, _vvvv_llll_ffff_mmmm_tttt - display error message in standard format and pass to logging and monitoring services SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_pppp_ffff_mmmm_tttt_...._hhhh_>>>> _iiii_nnnn_tttt _llll_ffff_mmmm_tttt_((((_FFFF_IIII_LLLL_EEEE _****_s_t_r_e_a_m_,,,, _llll_oooo_nnnn_gggg _f_l_a_g_s_,,,, _cccc_hhhh_aaaa_rrrr _****_f_o_r_m_a_t_,,,, _.... _.... _.... _////_**** _a_r_g_s _****_////_))))_;;;; _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_tttt_dddd_aaaa_rrrr_gggg_...._hhhh_>>>> _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_pppp_ffff_mmmm_tttt_...._hhhh_>>>> _iiii_nnnn_tttt _vvvv_llll_ffff_mmmm_tttt_((((_FFFF_IIII_LLLL_EEEE _****_s_t_r_e_a_m_,,,, _llll_oooo_nnnn_gggg _f_l_a_g_s_,,,, _cccc_hhhh_aaaa_rrrr _****_f_o_r_m_a_t_,,,, _vvvv_aaaa______llll_iiii_ssss_tttt _a_p_))))_;;;; DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN _llll_ffff_mmmm_tttt retrieves a format string from a locale-specific message database (unless _MMMM_MMMM______NNNN_OOOO_GGGG_EEEE_TTTT is specified) and uses it for _pppp_rrrr_iiii_nnnn_tttt_ffff style formatting of _a_r_g_s. The output is displayed on _s_t_r_e_a_m. If _s_t_r_e_a_m is _NNNN_UUUU_LLLL_LLLL, no output is displayed. _llll_ffff_mmmm_tttt encapsulates the output in the standard error message format (unless _MMMM_MMMM______NNNN_OOOO_SSSS_TTTT_DDDD is specified, in which case the output is simply _pppp_rrrr_iiii_nnnn_tttt_ffff-like). _llll_ffff_mmmm_tttt forwards its output to the logging and monitoring facility, even if _s_t_r_e_a_m is null. _llll_ffff_mmmm_tttt will also display the output on the console, with a date and time stamp, when _MMMM_MMMM______CCCC_OOOO_NNNN_SSSS_OOOO_LLLL_EEEE is specified (see below). If the _pppp_rrrr_iiii_nnnn_tttt_ffff format string is to be retrieved from a message database, the _f_o_r_m_a_t argument must have the following structure: _[[[[_c_a_t_a_l_o_g_::::_]]]]_m_s_g_n_u_m_::::_d_e_f_m_s_g. If _MMMM_MMMM______NNNN_OOOO_GGGG_EEEE_TTTT is specified, only the _d_e_f_m_s_g part must be specified. _c_a_t_a_l_o_g indicates the message database that contains the localized version of the format string. _c_a_t_a_l_o_g must be limited to 14 characters. These characters must be selected from a set of all character values, excluding _\\\\_0000 (null) and the ASCII codes for _//// (slash) and _:::: (colon). _m_s_g_n_u_m must be a positive number that indicates the index of the string into the message database. If _c_a_t_a_l_o_g does not exist in the locale (specified by the last call to _ssss_eeee_tttt_llll_oooo_cccc_aaaa_llll_eeee using the _LLLL_CCCC______AAAA_LLLL_LLLL or _LLLL_CCCC______MMMM_EEEE_SSSS_SSSS_AAAA_GGGG_EEEE_SSSS categories), or if the message number is out of bounds, _llll_ffff_mmmm_tttt attempts to retrieve the message from the _CCCC locale. If this second retrieval fails, _llll_ffff_mmmm_tttt uses the _d_e_f_m_s_g part of the _f_o_r_m_a_t argument. If _c_a_t_a_l_o_g is omitted, _llll_ffff_mmmm_tttt attempts to retrieve the string from the default catalog specified by the last call to _ssss_eeee_tttt_cccc_aaaa_tttt. In this case, the _f_o_r_m_a_t argument has the following structure: PPPPaaaaggggeeee 1111 llllffffmmmmtttt((((3333CCCC)))) llllffffmmmmtttt((((3333CCCC)))) _m_s_g_n_u_m_::::_d_e_f_m_s_g. _llll_ffff_mmmm_tttt outputs _MMMM_eeee_ssss_ssss_aaaa_gggg_eeee _nnnn_oooo_tttt _ffff_oooo_uuuu_nnnn_dddd_!!!!_!!!!\_n as the format string if: - _c_a_t_a_l_o_g is not a valid catalog name as defined above - no catalog is specified (either explicitly or via _ssss_eeee_tttt_cccc_aaaa_tttt) - _m_s_g_n_u_m is not a positive number - if no message could be retrieved from the message databases and _d_e_f_m_s_g was omitted The _f_l_a_g_s determine the type of output (that is, whether the _f_o_r_m_a_t should be interpreted as is or encapsulated in the standard message format), and the access to message catalogs to retrieve a localized version of _f_o_r_m_a_t. The _f_l_a_g_s are composed of several groups, and can take the following values (one from each group): _O_u_t_p_u_t _f_o_r_m_a_t _c_o_n_t_r_o_l _MMMM_MMMM______NNNN_OOOO_SSSS_TTTT_DDDD do not use the standard message format, interpret _f_o_r_m_a_t as a _pppp_rrrr_iiii_nnnn_tttt_ffff _f_o_r_m_a_t. Only _c_a_t_a_l_o_g _a_c_c_e_s_s _c_o_n_t_r_o_l _f_l_a_g_s, _c_o_n_s_o_l_e _d_i_s_p_l_a_y _c_o_n_t_r_o_l, and _l_o_g_g_i_n_g _i_n_f_o_r_m_a_t_i_o_n should be specified if _MMMM_MMMM______NNNN_OOOO_SSSS_TTTT_DDDD is used; all other flags will be ignored. _MMMM_MMMM______SSSS_TTTT_DDDD output using the standard message format (default, value 0). _C_a_t_a_l_o_g _a_c_c_e_s_s _c_o_n_t_r_o_l _MMMM_MMMM______NNNN_OOOO_GGGG_EEEE_TTTT do not retrieve a localized version of _f_o_r_m_a_t. In this case, only the _d_e_f_m_s_g part of the _f_o_r_m_a_t is specified. _MMMM_MMMM______GGGG_EEEE_TTTT retrieve a localized version of _f_o_r_m_a_t, from the _c_a_t_a_l_o_g, using _m_s_g_n_u_m as the index and _d_e_f_m_s_g as the default message (default, value 0). _S_e_v_e_r_i_t_y (_s_t_a_n_d_a_r_d _m_e_s_s_a_g_e _f_o_r_m_a_t _o_n_l_y) _MMMM_MMMM______HHHH_AAAA_LLLL_TTTT generates a localized version of _HHHH_AAAA_LLLL_TTTT. _MMMM_MMMM______EEEE_RRRR_RRRR_OOOO_RRRR generates a localized version of _EEEE_RRRR_RRRR_OOOO_RRRR (default, value 0). _MMMM_MMMM______WWWW_AAAA_RRRR_NNNN_IIII_NNNN_GGGG generates a localized version of _WWWW_AAAA_RRRR_NNNN_IIII_NNNN_GGGG. _MMMM_MMMM______IIII_NNNN_FFFF_OOOO generates a localized version of _IIII_NNNN_FFFF_OOOO. PPPPaaaaggggeeee 2222 llllffffmmmmtttt((((3333CCCC)))) llllffffmmmmtttt((((3333CCCC)))) Additional severities can be defined. Add-on severities can be defined with number-string pairs with numeric values from the range [5-255], using _aaaa_dddd_dddd_ssss_eeee_vvvv(3C). The numeric value ORed with other _f_l_a_g_s will generate the specified severity. If the severity is not defined, _llll_ffff_mmmm_tttt uses the string _SSSS_EEEE_VVVV_====_N where _N is replaced by the integer severity value passed in _f_l_a_g_s. Multiple severities passed in _f_l_a_g_s will not be detected as an error. Any combination of severities will be summed and the numeric value will cause the display of either a severity string (if defined) or the string _SSSS_EEEE_VVVV_====_N (if undefined). _A_c_t_i_o_n _MMMM_MMMM______AAAA_CCCC_TTTT_IIII_OOOO_NNNN specifies an action message. Any severity value is superseded and replaced by a localized version of _TTTT_OOOO _FFFF_IIII_XXXX. _C_o_n_s_o_l_e _d_i_s_p_l_a_y _c_o_n_t_r_o_l _MMMM_MMMM______CCCC_OOOO_NNNN_SSSS_OOOO_LLLL_EEEE display the message to the console in addition to the specified _s_t_r_e_a_m. _MMMM_MMMM______NNNN_OOOO_CCCC_OOOO_NNNN_SSSS_OOOO_LLLL_EEEE do not display the message to the console in addition to the specified _s_t_r_e_a_m (default, value 0). _L_o_g_g_i_n_g _i_n_f_o_r_m_a_t_i_o_n _M_a_j_o_r _c_l_a_s_s_i_f_i_c_a_t_i_o_n identifies the source of the condition. Identifiers are: _MMMM_MMMM______HHHH_AAAA_RRRR_DDDD (hardware), _MMMM_MMMM______SSSS_OOOO_FFFF_TTTT (software), and _MMMM_MMMM______FFFF_IIII_RRRR_MMMM (firmware). _M_e_s_s_a_g_e _s_o_u_r_c_e _s_u_b_c_l_a_s_s_i_f_i_c_a_t_i_o_n identifies the type of software in which the problem is spotted. Identifiers are: _MMMM_MMMM______AAAA_PPPP_PPPP_LLLL (application), _MMMM_MMMM______UUUU_TTTT_IIII_LLLL (utility), and _MMMM_MMMM______OOOO_PPPP_SSSS_YYYY_SSSS (operating system). SSSSttttaaaannnnddddaaaarrrrdddd EEEErrrrrrrroooorrrr MMMMeeeessssssssaaaaggggeeee FFFFoooorrrrmmmmaaaatttt _llll_ffff_mmmm_tttt displays error messages in the following format: _l_a_b_e_l_:::: _s_e_v_e_r_i_t_y_:::: _t_e_x_t If no _l_a_b_e_l was defined by a call to _ssss_eeee_tttt_llll_aaaa_bbbb_eeee_llll, the message is displayed in the format: _s_e_v_e_r_i_t_y_:::: _t_e_x_t If _llll_ffff_mmmm_tttt is called twice to display an error message and a helpful _a_c_t_i_o_n or recovery message, the output can look like: PPPPaaaaggggeeee 3333 llllffffmmmmtttt((((3333CCCC)))) llllffffmmmmtttt((((3333CCCC)))) _l_a_b_e_l_:::: _s_e_v_e_r_i_t_y_:::: _t_e_x_t _l_a_b_e_l_:::: _TTTT_OOOO _FFFF_IIII_XXXX_:::: _t_e_x_t vvvvllllffffmmmmtttt _vvvv_llll_ffff_mmmm_tttt is the same as _llll_ffff_mmmm_tttt except that instead of being called with a variable number of arguments, it is called with an argument list as defined by the _ssss_tttt_dddd_aaaa_rrrr_gggg_...._hhhh header file. The _ssss_tttt_dddd_aaaa_rrrr_gggg_...._hhhh header file defines the type _vvvv_aaaa______llll_iiii_ssss_tttt and a set of macros for advancing through a list of arguments whose number and types may vary. The argument _a_p to _vvvv_llll_ffff_mmmm_tttt is of type _vvvv_aaaa______llll_iiii_ssss_tttt. This argument is used with the _ssss_tttt_dddd_aaaa_rrrr_gggg_...._hhhh header file macros _vvvv_aaaa______ssss_tttt_aaaa_rrrr_tttt, _vvvv_aaaa______aaaa_rrrr_gggg and _vvvv_aaaa______eeee_nnnn_dddd [see _vvvv_aaaa______ssss_tttt_aaaa_rrrr_tttt, _vvvv_aaaa______aaaa_rrrr_gggg, and _vvvv_aaaa______eeee_nnnn_dddd in _ssss_tttt_dddd_aaaa_rrrr_gggg(5)]. The EXAMPLE sections below show their use. The macro _vvvv_aaaa______aaaa_llll_iiii_ssss_tttt is used as the parameter list in a function definition as in the function called _eeee_rrrr_rrrr_oooo_rrrr in the example below. The macro _vvvv_aaaa______ssss_tttt_aaaa_rrrr_tttt_((((_a_p_,,,, _)))), where _a_p is of type _vvvv_aaaa______llll_iiii_ssss_tttt, must be called before any attempt to traverse and access unnamed arguments. Calls to _vvvv_aaaa______aaaa_rrrr_gggg_((((_a_p_,,,, _a_t_y_p_e_)))) traverse the argument list. Each execution of _vvvv_aaaa______aaaa_rrrr_gggg expands to an expression with the value and type of the next argument in the list _a_p, which is the same object initialized by _vvvv_aaaa______ssss_tttt_aaaa_rrrr_tttt. The argument _a_t_y_p_e is the type that the returned argument is expected to be. The _vvvv_aaaa______eeee_nnnn_dddd_((((_a_p_)))) macro must be invoked when all desired arguments have been accessed. [The argument list in _a_p can be traversed again if _vvvv_aaaa______ssss_tttt_aaaa_rrrr_tttt is called again after _vvvv_aaaa______eeee_nnnn_dddd.] In the example below, _vvvv_aaaa______aaaa_rrrr_gggg is executed first to retrieve the format string passed to _eeee_rrrr_rrrr_oooo_rrrr. The remaining _eeee_rrrr_rrrr_oooo_rrrr arguments, _a_r_g_1, _a_r_g_2, . . ., are given to _vvvv_llll_ffff_mmmm_tttt in the argument _a_p. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS llllffffmmmmtttt eeeexxxxaaaammmmpppplllleeee 1111 _ssss_eeee_tttt_llll_aaaa_bbbb_eeee_llll_((((_""""_UUUU_XXXX_::::_tttt_eeee_ssss_tttt_""""_))))_;;;; _llll_ffff_mmmm_tttt_((((_ssss_tttt_dddd_eeee_rrrr_rrrr_,,,, _MMMM_MMMM______EEEE_RRRR_RRRR_OOOO_RRRR_||||_MMMM_MMMM______CCCC_OOOO_NNNN_SSSS_OOOO_LLLL_EEEE_||||_MMMM_MMMM______SSSS_OOOO_FFFF_TTTT_||||_MMMM_MMMM______UUUU_TTTT_IIII_LLLL_,,,, _""""_tttt_eeee_ssss_tttt_::::_2222_::::_CCCC_aaaa_nnnn_nnnn_oooo_tttt _oooo_pppp_eeee_nnnn _ffff_iiii_llll_eeee_:::: _%%%%_ssss_\\\\_nnnn_""""_,,,, _ssss_tttt_rrrr_eeee_rrrr_rrrr_oooo_rrrr_((((_eeee_rrrr_rrrr_nnnn_oooo_))))_))))_;;;; displays the message to _s_t_d_e_r_r and to the console and makes it available for logging: _UUUU_XXXX_::::_tttt_eeee_ssss_tttt_:::: _EEEE_RRRR_RRRR_OOOO_RRRR_:::: _CCCC_aaaa_nnnn_nnnn_oooo_tttt _oooo_pppp_eeee_nnnn _ffff_iiii_llll_eeee_:::: _NNNN_oooo _ssss_uuuu_cccc_hhhh _ffff_iiii_llll_eeee _oooo_rrrr _dddd_iiii_rrrr_eeee_cccc_tttt_oooo_rrrr_yyyy llllffffmmmmtttt eeeexxxxaaaammmmpppplllleeee 2222 _ssss_eeee_tttt_llll_aaaa_bbbb_eeee_llll_((((_""""_UUUU_XXXX_::::_tttt_eeee_ssss_tttt_""""_))))_;;;; _llll_ffff_mmmm_tttt_((((_ssss_tttt_dddd_eeee_rrrr_rrrr_,,,, _MMMM_MMMM______IIII_NNNN_FFFF_OOOO_||||_MMMM_MMMM______SSSS_OOOO_FFFF_TTTT_||||_MMMM_MMMM______UUUU_TTTT_IIII_LLLL_,,,, _""""_tttt_eeee_ssss_tttt_::::_2222_3333_::::_tttt_eeee_ssss_tttt _ffff_aaaa_cccc_iiii_llll_iiii_tttt_yyyy _iiii_ssss _eeee_nnnn_aaaa_bbbb_llll_eeee_dddd_\\\\_nnnn_""""_))))_;;;; displays the message to _s_t_d_e_r_r and makes it available for logging: _UUUU_XXXX_::::_tttt_eeee_ssss_tttt_:::: _IIII_NNNN_FFFF_OOOO_:::: _tttt_eeee_ssss_tttt _ffff_aaaa_cccc_iiii_llll_iiii_tttt_yyyy _eeee_nnnn_aaaa_bbbb_llll_eeee_dddd vvvvllllffffmmmmtttt eeeexxxxaaaammmmpppplllleeee The following demonstrates how _vvvv_llll_ffff_mmmm_tttt could be used to write an _eeee_rrrr_rrrr_llll_oooo_gggg routine: PPPPaaaaggggeeee 4444 llllffffmmmmtttt((((3333CCCC)))) llllffffmmmmtttt((((3333CCCC)))) _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_pppp_ffff_mmmm_tttt_...._hhhh_>>>> _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_tttt_dddd_aaaa_rrrr_gggg_...._hhhh_>>>> _.... _.... _.... _////_**** _**** _eeee_rrrr_rrrr_llll_oooo_gggg _ssss_hhhh_oooo_uuuu_llll_dddd _bbbb_eeee _cccc_aaaa_llll_llll_eeee_dddd _llll_iiii_kkkk_eeee _**** _eeee_rrrr_rrrr_llll_oooo_gggg_((((_llll_oooo_gggg______iiii_nnnn_ffff_oooo_,,,, _ffff_oooo_rrrr_mmmm_aaaa_tttt_,,,, _aaaa_rrrr_gggg_1111_,,,, _...._...._...._))))_;;;; _****_//// _vvvv_oooo_iiii_dddd _eeee_rrrr_rrrr_llll_oooo_gggg_((((_llll_oooo_nnnn_gggg _llll_oooo_gggg______iiii_nnnn_ffff_oooo_,,,, _cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_ffff_oooo_rrrr_mmmm_aaaa_tttt_,,,, _...._...._...._)))) _{{{{ _vvvv_aaaa______llll_iiii_ssss_tttt _aaaa_pppp_;;;; _vvvv_aaaa______ssss_tttt_aaaa_rrrr_tttt_((((_aaaa_pppp_,,,, _ffff_oooo_rrrr_mmmm_aaaa_tttt_))))_;;;; _((((_vvvv_oooo_iiii_dddd_)))) _vvvv_llll_ffff_mmmm_tttt_((((_ssss_tttt_dddd_eeee_rrrr_rrrr_,,,, _llll_oooo_gggg______iiii_nnnn_ffff_oooo_||||_MMMM_MMMM______EEEE_RRRR_RRRR_OOOO_RRRR_,,,, _ffff_oooo_rrrr_mmmm_aaaa_tttt_,,,, _aaaa_pppp_))))_;;;; _vvvv_aaaa______eeee_nnnn_dddd_((((_aaaa_pppp_))))_;;;; _((((_vvvv_oooo_iiii_dddd_)))) _aaaa_bbbb_oooo_rrrr_tttt_((((_))))_;;;; _}}}} SSSSEEEEEEEE AAAALLLLSSSSOOOO _llll_ffff_mmmm_tttt(1), _pppp_ffff_mmmm_tttt(1), _aaaa_dddd_dddd_ssss_eeee_vvvv(3C), _gggg_eeee_tttt_tttt_xxxx_tttt(3C), _ssss_eeee_tttt_cccc_aaaa_tttt(3C), _ssss_eeee_tttt_llll_aaaa_bbbb_eeee_llll(3C), _ssss_eeee_tttt_llll_oooo_cccc_aaaa_llll_eeee(3C), _pppp_rrrr_iiii_nnnn_tttt_ffff(3S), _eeee_nnnn_vvvv_iiii_rrrr_oooo_nnnn(5), _ssss_tttt_dddd_aaaa_rrrr_gggg(5) DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS On success, _llll_ffff_mmmm_tttt and _vvvv_llll_ffff_mmmm_tttt return the number of bytes transmitted. On failure, they return a negative value: -1 write error to _s_t_r_e_a_m -2 cannot log and/or display at console. PPPPaaaaggggeeee 5555 
